home *** CD-ROM | disk | FTP | other *** search
/ SPACE 1 / SPACE - Library 1 - Volume 1.iso / misc~1 / 199 / readme.doc < prev    next >
Text File  |  1988-03-14  |  10KB  |  227 lines
  1. UPDATE - Shareware Atari 520ST C compiler - version 1.2
  2.          copyright 1987 - Mark A. Johnson
  3.  
  4. This is an update to the shareware C compiler I've distributed in
  5. the past.  It contains updates to the compiler, assembler, libraries and
  6. startup routines.  It also contains a UN*X-style "make" program (mk.c)
  7. and a tool to help figure out crashes (bug.c).  Read the source for info 
  8. on how to use mk and bug.  To save space, I've only included the source
  9. for the libaries and tools.  Use the compiler to build them:
  10.  
  11.     cc -o lib.a lib.c
  12.     cc -o gem.a gem.c
  13.  
  14.     cc mk.c
  15.     as -o mk.ttp ttp.s yc.out -l lib.a
  16.     cc bug.c
  17.     as -o bug.ttp ttp.s yc.out -l lib.a
  18.  
  19. This version fixes two bugs in the "register" storage class code generation.
  20. The previous update (version 1.1) had register variables in the library
  21. code which will not work.  If you wish to continue to use 1.1 (instead of
  22. downloaded 1.2) you must delete the storage class "register" from the 
  23. variable declarations in gem.c and lib.c and recompile the libraries.
  24. (I'd just downloading the update.)
  25.  
  26. What follows is the original README.DOC included with the distribution disk,
  27. updated with recent changes.  If you need the distribution disk, send me a 
  28. blank disk at the address listed below.  (Judged by the previous responses,
  29. shareware == freeware and hardly anyone writes to say thanks.  That's okay, 
  30. as long as we're all having fun).
  31.  
  32.     Mark A. Johnson
  33.         85 Coleman Avenue
  34.         Red Bank, NJ 07701
  35.  
  36. This disk contains a limited shareware C compiler for your use and enjoyment.
  37. You should find a number of directories on this disk which contain the 
  38. following files:
  39.  
  40.   bin
  41.     cc.ttp    - translates C code to intermediate code
  42.     as.ttp    - translates intermediate code to machine code
  43.     hd.ttp    - hex dump utility
  44.     cat.ttp    - file concatenation utility
  45.     grep.ttp    - utility to search for a string in a file
  46.     date.ttp    - displays (sets) the current date and time
  47.     ue.ttp    - public domain microEmacs editor 
  48.     mk.ttp    - simple UN*X style "make" program
  49.     bug.ttp    - answers the question "where did it crash"
  50.  
  51.   lib
  52.     prg.s    - startup intermediate code for .PRG programs
  53.     ttp.s    - startup intermediate code for .TTP programs
  54.     lib.a    - library used to create .TTP programs
  55.     gem.a    - library used to create .PRG programs
  56.     lib.c    - c code for lib.a
  57.     gem.c       - c code for gem.a
  58.     stdio.h    - standard i/o header
  59.     setjmp.h    - header for setjmp/longjmp routines
  60.     gem.h    - header for GEM AES routines
  61.  
  62.   src
  63.     ss.c    - source for a simple spreadsheet program
  64.     cat.c    - source the file concatenation program
  65.     grep.c    - source for the string search program
  66.     hd.c        - source for the hex dump program
  67.     mk.c    - source for the make program
  68.     bug.c    - source for the bug finder program
  69.  
  70. You will also find the following files in the root directory:
  71.  
  72.     rmd209.acc    - public domain ramdisk accessory
  73.     command.tos    - public domain command line interpreter
  74.     boot.bat    - copy tools into the ramdisk
  75.     as.doc    - documentation on the intermediate code
  76.     err.doc    - documentation on the compiler error messages
  77.     readme.doc    - this file
  78.  
  79. The compiler (cc.ttp) is preprocessor, parser, and code generator all rolled
  80. into a single program.  Please refer to the "C Programming Language" by K&R.
  81. The compiler has the following features, limitations, and shortcomings:
  82.  
  83.   features
  84.     - symbol names can be any length
  85.     - built-in "trap" generator "trap(NUM, arg1, arg2, ...)"
  86.     - structure assignments
  87.     - register variables
  88.  
  89.   limitations
  90.     - Initialization should be done carefully.  No type checking 
  91.       is done between the initializing value and the type of the variable
  92.       being initialized.  This is crude but it works.  Accepted initializer
  93.       values are (long or short) constant expressions, strings, and symbols.
  94.       Local variables can be initialized with any valid expression.
  95.  
  96.   what's missing
  97.     - type specifiers: float double auto
  98.     - goto and labels
  99.  
  100. The output of the compiler is ascii text and each line maps into a 
  101. single instruction.  This intermediate code is as terse as I can make it (to
  102. save disk space) but is still readable (by me at least).  (I have plans to 
  103. improve this to make things easier for an optimizer).  The output of the 
  104. compiler is always placed in a file called "yc.out" in the current directory.
  105. Any error messages are displayed on the screen.  If "-o filename" is present
  106. on the command line, output will be placed in the specified file instead of
  107. YC.OUT.
  108.  
  109. The assembler (as.ttp) reads the intermediate code in a single pass and 
  110. keeps everything in memory before generating the file "ya.out" in the 
  111. current directory.  The size limit of the program to be compiled is basically
  112. the size of the available memory.  The "ya.out" file should be renamed to 
  113. one of the standard extensions (.TTP, .PRG, .TOS) before executing it.  
  114. The command line of the assembler should always list a startup file 
  115. first (see ttp.s or prg.s) then the intermediate files of the program, 
  116. then "-L" followed by any libraries.  Any errors encountered by the 
  117. assembler terminates assembly.  A "-m" argument to the assembler will 
  118. include the symbol table (standard Atari format) in the output file.  
  119. A "-o filename" argument will place the output in the specified file instead
  120. of in YA.OUT.
  121.  
  122. A library is simply intermediate code, but is handled differently by the 
  123. assembler than regular intermediate code.  Intermediate code (the 
  124. files before "-L") are read and processed directly; all symbols and
  125. code are accepted without question.  A library is read without processing 
  126. until a symbol is found that is needed but not defined.  From that point 
  127. on, the library is read and processed until the next symbol is encountered.
  128. At the next symbol, the "needed but not defined" test is applied again 
  129. and processing or scanning continues as necessary.
  130.  
  131. The libraries include TOS, VDI, and AES routines taken from the Abacus books.
  132. I plan to document the library routines later.  I have also included basic
  133. <stdio.h> routines.  I have included the source for lib.a and gem.a (see
  134. lib.c and gem.c).  A lot of library routines you would expect to see are
  135. missing, and for that I apologize.  I have recently added scanf, a full
  136. printf, and a real malloc/realloc/free memory allocator package to lib.c
  137.  
  138. Creating .TTP programs is straightforward and better tested than .PRG (GEM) 
  139. program creation.  In a .TTP process, the main function is called with 
  140. the standard arguments:
  141.  
  142.     main(argc, argv) int argc; char *argv[];
  143.  
  144. Redirection of input and output using >outfile, >>appendfile, or <infile 
  145. on the command line is handled by a startup routine linked into the 
  146. compiled program.  Reads and writes to the screen are built to map '\n' 
  147. to/from "\n\r".
  148.  
  149. Support for GEM programs (.PRG) is not completely debugged.  The GEM.A 
  150. library includes all the VDI and AES functions in the Abacus books,
  151. but has not been extensively tested.  The VDI routines work and 
  152. the window routines, form_alert, and evnt_multi of AES are working.  
  153. My stumbling block right now is adequate documentation 
  154. that would enable me to build a (working) Resource Construction Set.  
  155. I'm working on it...
  156.  
  157. Let me give you an example of how I use these tools.  I make up an
  158. auto-booting disk from the distribution disk which contains all the files
  159. I normally use when compiling (as.ttp, cc.ttp, the libraries, starup files,
  160. and as many tools as can fit in the ramdisk).  I use Moshe Braner's AUTODISK
  161. which sets the date and copies stuff to ramdisk very quickly.  MK works
  162. best when the date is accurately set.
  163.  
  164. I then insert a working disk (I only have a single floppy!).
  165. I use microEmacs (ue.ttp) to create or edit C programs.  The MK.TTP program
  166. has built-in rules that enable it to build .TTP or .PRG programs out of
  167. .C source files without any makefile needed.  For example, 
  168.  
  169.     mk grep.ttp
  170.  
  171. will compile the program grep.c and create an executable called grep.ttp.
  172. If the C program is contained in a number of files, I normally create a
  173. makefile MK.TTP can use.  Intermediate files are created from the C source
  174. (again a built-in rule in MK.TTP) and finally the object is linked together
  175. by an entry in the makefile.  For example, say I have a spreadsheet program
  176. composed of four files: main.c, io.c, calc.c, and display.c.  The following
  177. makefile would do the trick (without the indentations!)
  178.  
  179.     # makefile for a (mythical) spreadsheet program
  180.  
  181.     OBJ = main.s io.s calc.s display.s
  182.  
  183.     ss.ttp: $(OBJ)
  184.         d:as.ttp d:ttp.s $(OBJ) -L d:lib.a
  185.     
  186.     io.c main.c display.c: stdio.h
  187.  
  188.  
  189. With the above, I can build the spreadsheet after editing with
  190.  
  191.     mk ss.ttp
  192.  
  193. Only those files that need to be compiled will be compiled.  When everything
  194. is compiled then the objects will be linked together to form the executable.
  195. The source for MK.TTP is included on this disk (SRC\MK.C), so take a look in
  196. there for more information on how it works.  If you insist on doing things by
  197. hand, then
  198.  
  199.     cc file.c
  200.  
  201. will compile FILE.C into intermediate code, which is found in YC.OUT in the
  202. current directory.  You then use 
  203.  
  204.     as d:ttp.s yc.out -L d:lib.a
  205.  
  206. to assemble and link the startup file TTP.S, the compiler output YC.OUT and
  207. the library LIB.A.  For GEM programs, you can replace TTP.S with PRG.S 
  208. and add GEM.A after the -L.
  209.  
  210. I bought my 520ST in April 1986.  Almost all the software I have is either 
  211. public domain or shareware.  I have supported the shareware idea in the past,
  212. but I'd like to see it happen for myself.  If you like what you find here,
  213. please send a donation along with your name and address.  I'd like to run a
  214. newsletter to discuss bugs, enhancements, and hints.  There is a lot 
  215. I would like to do with this in the future.  Many of the limitations are
  216. easy to fix, and I really do need a Resource Construction Set (if I can 
  217. only figure out how to make object trees that work!).  I hope you enjoy
  218. this software.  It is not for sale by anyone, and I reserve all rights 
  219. to its ownership.  Feel free to pass it on to other ST owners, but please
  220. pass on the whole disk, including this "readme" file.  I welcome any comments
  221. you may have; send mail to:
  222.  
  223.     Mark A. Johnson
  224.     85 Coleman Ave
  225.     Red Bank, NJ 07701
  226.  
  227.